Sprite 1984

home *** CD-ROM | disk | FTP | other *** search

/ Sprite 1984 - 1993 / Sprite 1984 - 1993.iso / man / lib.fmt / sunrpc / rpc.man < prev next >

Wrap

Text File | 1989-03-16 | 41.1 KB | 991 lines

RPC C Library Procedures RPC NNAAMMEE rpc - library routines for remote procedure calls SSYYNNOOPPSSIISS AANNDD DDEESSCCRRIIPPTTIIOONN These routines allow C programs to make procedure calls on other machines across the network. First, the client calls a procedure to send a data packet to the server. Upon receipt of the packet, the server calls a dispatch routine to perform the requested service, and then sends back a reply. Finally, the procedure call returns to the client. ##iinncclluuddee <<rrppcc//rrppcc..hh>> vvooiidd aauutthh__ddeessttrrooyy((aauutthh)) AAUUTTHH **aauutthh;; A macro that destroys the authentication information associated with aauutthh. Destruction usually involves deallocation of private data structures. The use of aauutthh is undefined after calling aauutthh__ddeessttrrooyy. AAUUTTHH ** aauutthhnnoonnee__ccrreeaattee(()) Creates and returns an RPC authentication handle that passes nonusable authentication information with each remote procedure call. This is the default authentica- tion used by RPC. AAUUTTHH ** aauutthhuunniixx__ccrreeaattee((hhoosstt,, uuiidd,, ggiidd,, lleenn,, aauupp__ggiiddss)) cchhaarr **hhoosstt;; iinntt uuiidd,, ggiidd,, lleenn,, **aauupp..ggiiddss;; Creates and returns an RPC authentication handle that contains authentication information. The parameter hhoosstt is the name of the machine on which the informa- tion was created; uuiidd is the user's user ID ; ggiidd is the user's current group ID ; lleenn and aauupp__ggiiddss refer to a counted array of groups to which the user belongs. It is easy to impersonate a user. AAUUTTHH ** aauutthhuunniixx__ccrreeaattee__ddeeffaauulltt(()) Calls aauutthhuunniixx__ccrreeaattee with the appropriate parameters. ccaallllrrppcc((hhoosstt,, pprrooggnnuumm,, vveerrssnnuumm,, pprrooccnnuumm,, iinnpprroocc,, iinn,, oouuttpprroocc,, oouutt)) cchhaarr **hhoosstt;; uu__lloonngg pprrooggnnuumm,, vveerrssnnuumm,, pprrooccnnuumm;; cchhaarr **iinn,, **oouutt;; Sprite v1.0 3 November 1987 1 RPC C Library Procedures RPC xxddrrpprroocc__tt iinnpprroocc,, oouuttpprroocc;; Calls the remote procedure associated with pprrooggnnuumm, vveerrssnnuumm, and pprrooccnnuumm on the machine, hhoosstt. The parame- ter iinn is the address of the procedure's argument(s), and oouutt is the address of where to place the result(s); iinnpprroocc is used to encode the procedure's parameters, and oouuttpprroocc is used to decode the procedure's results. This routine returns zero if it succeeds, or the value of eennuumm ccllnntt__ssttaatt cast to an integer if it fails. The routine ccllnntt__ppeerrrrnnoo is handy for translating failure statuses into messages. Warning: calling remote procedures with this routine uses UDP/IP as a transport; see ccllnnttuuddpp__ccrreeaattee for res- trictions. You do not have control of timeouts or authentication using this routine. eennuumm ccllnntt__ssttaatt ccllnntt__bbrrooaaddccaasstt((pprrooggnnuumm,, vveerrssnnuumm,, pprrooccnnuumm,, iinnpprroocc,, iinn,, oouuttpprroocc,, oouutt,, eeaacchhrreessuulltt)) uu__lloonngg pprrooggnnuumm,, vveerrssnnuumm,, pprrooccnnuumm;; cchhaarr **iinn,, **oouutt;; xxddrrpprroocc__tt iinnpprroocc,, oouuttpprroocc;; rreessuullttpprroocc__tt eeaacchhrreessuulltt;; Like ccaallllrrppcc, except the call message is broadcast to all locally connected broadcast nets. Each time it receives a response, this routine calls eeaacchhrreessuulltt, whose form is: eeaacchhrreessuulltt((oouutt,, aaddddrr)) cchhaarr **oouutt;; ssttrruucctt ssoocckkaaddddrr__iinn **aaddddrr;; where oouutt is the same as oouutt passed to ccllnntt__bbrrooaaddccaasstt, except that the remote procedure's output is decoded there; aaddddrr points to the address of the machine that sent the results. If eeaacchhrreessuulltt returns zero, ccllnntt__bbrrooaaddccaasstt waits for more replies; otherwise it returns with appropriate status. Warning: broadcast sockets are limited in size to the maximum transfer unit of the data link. For ethernet, this value is 1500 bytes. eennuumm ccllnntt__ssttaatt ccllnntt__ccaallll((ccllnntt,, pprrooccnnuumm,, iinnpprroocc,, iinn,, oouuttpprroocc,, oouutt,, ttoouutt)) CCLLIIEENNTT **ccllnntt;; uu__lloonngg pprrooccnnuumm;; xxddrrpprroocc__tt iinnpprroocc,, oouuttpprroocc;; cchhaarr **iinn,, **oouutt;; ssttrruucctt ttiimmeevvaall ttoouutt;; A macro that calls the remote procedure pprrooccnnuumm Sprite v1.0 3 November 1987 2 RPC C Library Procedures RPC associated with the client handle, ccllnntt, which is obtained with an RPC client creation routine such as ccllnntt__ccrreeaattee. The parameter iinn is the address of the procedure's argument(s), and oouutt is the address of where to place the result(s); iinnpprroocc is used to encode the procedure's parameters, and oouuttpprroocc is used to decode the procedure's results; ttoouutt is the time allowed for results to come back. ccllnntt__ddeessttrrooyy((ccllnntt)) CCLLIIEENNTT **ccllnntt;; A macro that destroys the client's RPC handle. Destruc- tion usually involves deallocation of private data structures, including ccllnntt itself. Use of ccllnntt is undefined after calling ccllnntt__ddeessttrrooyy. If the RPC library opened the associated socket, it will close it also. Otherwise, the socket remains open. CCLLIIEENNTT ** ccllnntt__ccrreeaattee ((hhoosstt,, pprroogg,, vveerrss,, pprroottoo)) cchhaarr **hhoosstt;; uu__lloonngg pprroogg,, vveerrss;; cchhaarr **pprroottoo;; Generic client creation routine. hhoosstt identifies the name of the remote host where the server is located. pprroottoo indicates which kind of transport protocol to use. The currently supported values for this field are ``udp'' and ``tcp''. Default timeouts are set, but can be modified using ccllnntt__ccoonnttrrooll.. Warning: Using UDP has its shortcomings. Since UDP- based RPC messages can only hold up to 8 Kbytes of encoded data, this transport cannot be used for pro- cedures that take large arguments or return huge results. bbooooll__tt ccllnntt__ccoonnttrrooll((ccll,, rreeqq,, iinnffoo)) CCLLIIEENNTT **ccll;; cchhaarr **iinnffoo;; A macro used to change or retrieve various information about a client object. rreeqq indicates the type of operation, and iinnffoo is a pointer to the information. For both UDP and TCP, the supported values of rreeqq and their argument types and what they do are: CLSET_TIMEOUT struct timeval set total timeout CLGET_TIMEOUT struct timeval get total timeout Note: if you set the timeout using ccllnntt__ccoonnttrrooll, the Sprite v1.0 3 November 1987 3 RPC C Library Procedures RPC timeout parameter passed to ccllnntt__ccaallll will be ignored in all future calls. CLGET_SERVER_ADDR struct sockaddr get server's address The following operations are valid for UDP only: CLSET_RETRY_TIMEOUT struct timevalset the retry timeout CLGET_RETRY_TIMEOUT struct timevalget the retry timeout The retry timeout is the time that UDP RPC waits for the server to reply before retransmitting the request. ccllnntt__ffrreeeerreess((ccllnntt,, oouuttpprroocc,, oouutt)) CCLLIIEENNTT **ccllnntt;; xxddrrpprroocc__tt oouuttpprroocc;; cchhaarr **oouutt;; A macro that frees any data allocated by the RPC/XDR system when it decoded the results of an RPC call. The parameter oouutt is the address of the results, and oouuttpprroocc is the XDR routine describing the results in simple primitives. This routine returns one if the results were successfully freed, and zero otherwise. vvooiidd ccllnntt__ggeetteerrrr((ccllnntt,, eerrrrpp)) CCLLIIEENNTT **ccllnntt;; ssttrruucctt rrppcc__eerrrr **eerrrrpp;; A macro that copies the error structure out of the client handle to the structure at address eerrrrpp. vvooiidd ccllnntt__ppccrreeaatteeeerrrroorr((ss)) cchhaarr **ss;; Prints a message to standard error indicating why a client RPC handle could not be created. The message is prepended with string ss and a colon. Used when a ccllnntt__ccrreeaattee, ccllnnttrraaww__ccrreeaattee, ccllnnttttccpp__ccrreeaattee, or ccllnnttuuddpp__ccrreeaattee call fails. vvooiidd ccllnntt__ppeerrrrnnoo((ssttaatt)) eennuumm ccllnntt__ssttaatt ssttaatt;; Prints a message to standard error corresponding to the condition indicated by ssttaatt. Used after ccaallllrrppcc. ccllnntt__ppeerrrroorr((ccllnntt,, ss)) CCLLIIEENNTT **ccllnntt;; cchhaarr **ss;; Prints a message to standard error indicating why an RPC call failed; ccllnntt is the handle used to do the Sprite v1.0 3 November 1987 4 RPC C Library Procedures RPC call. The message is prepended with string ss and a colon. Used after ccllnntt__ccaallll. cchhaarr ** ccllnntt__ssppccrreeaatteeeerrrroorr cchhaarr **ss;; Like ccllnntt__ppccrreeaatteeeerrrroorr, except that it returns a string instead of printing to the standard error. Bugs: returns pointer to static data that is overwrit- ten on each call. cchhaarr ** ccllnntt__ssppeerrrrnnoo((ssttaatt)) eennuumm ccllnntt__ssttaatt ssttaatt;; Takes the same arguments as ccllnntt__ppeerrrrnnoo, but instread of sending a message to the standard error indicating why an RPC call failed, it returns a pointer to a string which contains the message. The string ends with a newline. ccllnntt__ssppeerrrrnnoo is used instead of ccllnntt__ppeerrrrnnoo if the pro- gram doesn't have a standard error (as a program run- ning as a server quite likely doesn't), or if the pro- grammer doesn't want the message to be output with pprriinnttff, or if a message format different than that sup- ported by ccllnntt__ppeerrrrnnoo is to be used. Note: unlike ccllnntt__ssppeerrrroorr and ccllnntt__ssppccrreeaatteerrrroorr, ccllnntt__ssppeerrrrnnoo does not return pointer to static data so the result will not get overwritten on each call. cchhaarr ** ccllnntt__ssppeerrrroorr((rrppcchh,, ss)) CCLLIIEENNTT **rrppcchh;; cchhaarr **ss;; Like ccllnntt__ppeerrrroorr, except that (like ccllnntt__ssppeerrrrnnoo) it returns a string instead of printing to standard error. Bugs: returns pointer to static data that is overwrit- ten on each call. CCLLIIEENNTT ** ccllnnttrraaww__ccrreeaattee((pprrooggnnuumm,, vveerrssnnuumm)) uu__lloonngg pprrooggnnuumm,, vveerrssnnuumm;; This routine creates a toy RPC client for the remote program pprrooggnnuumm, version vveerrssnnuumm. The transport used to pass messages to the service is actually a buffer within the process's address space, so the Sprite v1.0 3 November 1987 5 RPC C Library Procedures RPC corresponding RPC server should live in the same address space; see ssvvccrraaww__ccrreeaattee. This allows simula- tion of RPC and acquisition of RPC overheads, such as round trip times, without any kernel interference. This routine returns NULL if it fails. CCLLIIEENNTT ** ccllnnttttccpp__ccrreeaattee((aaddddrr,, pprrooggnnuumm,, vveerrssnnuumm,, ssoocckkpp,, sseennddsszz,, rreeccvvsszz)) ssttrruucctt ssoocckkaaddddrr__iinn **aaddddrr;; uu__lloonngg pprrooggnnuumm,, vveerrssnnuumm;; iinntt **ssoocckkpp;; uu__iinntt sseennddsszz,, rreeccvvsszz;; This routine creates an RPC client for the remote pro- gram pprrooggnnuumm, version vveerrssnnuumm; the client uses TCP/IP as a transport. The remote program is located at Inter- net address **aaddddrr. If aaddddrr-->>ssiinn__ppoorrtt is zero, then it is set to the actual port that the remote program is listening on (the remote ppoorrttmmaapp service is consulted for this information). The parameter ssoocckkpp is a socket; if it is RRPPCC__AANNYYSSOOCCKK, then this routine opens a new one and sets ssoocckkpp. Since TCP-based RPC uses buffered I/O , the user may specify the size of the send and receive buffers with the parameters sseennddsszz and rreeccvvsszz; values of zero choose suitable defaults. This routine returns NULL if it fails. CCLLIIEENNTT ** ccllnnttuuddpp__ccrreeaattee((aaddddrr,, pprroonnuumm,, vveerrssnnuumm,, wwaaiitt,, ssoocckkpp)) ssttrruucctt ssoocckkaaddddrr__iinn **aaddddrr;; uu__lloonngg pprrooggnnuumm,, vveerrssnnuumm;; ssttrruucctt ttiimmeevvaall wwaaiitt;; iinntt **ssoocckkpp;; This routine creates an RPC client for the remote pro- gram pprrooggnnuumm, version vveerrssnnuumm; the client uses use UDP/IP as a transport. The remote program is located at Internet address aaddddrr. If aaddddrr-->>ssiinn__ppoorrtt is zero, then it is set to actual port that the remote program is listening on (the remote ppoorrttmmaapp service is consulted for this information). The parameter ssoocckkpp is a socket; if it is RRPPCC__AANNYYSSOOCCKK , then this routine opens a new one and sets ssoocckkpp. The UDP transport resends the call message in intervals of wwaaiitt time until a response is received or until the call times out. The total time for the call to time out is specified by ccllnntt__ccaallll. Warning: since UDP-based RPC messages can only hold up to 8 Kbytes of encoded data, this transport cannot be used for procedures that take large arguments or return huge results. Sprite v1.0 3 November 1987 6 RPC C Library Procedures RPC vvooiidd ggeett__mmyyaaddddrreessss((aaddddrr)) ssttrruucctt ssoocckkaaddddrr__iinn **aaddddrr;; Stuffs the machine's IP address into **aaddddrr, without consulting the library routines that deal with //eettcc//hhoossttss. The port number is always set to hhttoonnss( PMAPPORT ). ssttrruucctt ppmmaapplliisstt ** ppmmaapp__ggeettmmaappss((aaddddrr)) ssttrruucctt ssoocckkaaddddrr__iinn **aaddddrr;; A user interface to the ppoorrttmmaapp service, which returns a list of the current RPC program-to-port mappings on the host located at IP address **aaddddrr. This routine can return NULL . The command rrppcciinnffoo --pp uses this routine. uu__sshhoorrtt ppmmaapp__ggeettppoorrtt((aaddddrr,, pprrooggnnuumm,, vveerrssnnuumm,, pprroottooccooll)) ssttrruucctt ssoocckkaaddddrr__iinn **aaddddrr;; uu__lloonngg pprrooggnnuumm,, vveerrssnnuumm,, pprroottooccooll;; A user interface to the ppoorrttmmaapp service, which returns the port number on which waits a service that supports program number pprrooggnnuumm, version vveerrssnnuumm, and speaks the transport protocol associated with pprroottooccooll. The value of pprroottooccooll is most likely IIPPPPRROOTTOO__UUDDPP or IIPPPPRROOTTOO__TTCCPP. A return value of zero means that the mapping does not exist or that the RPC system failured to contact the remote ppoorrttmmaapp service. In the latter case, the global variable rrppcc__ccrreeaatteeeerrrr contains the RPC status. eennuumm ccllnntt__ssttaatt ppmmaapp__rrmmttccaallll((aaddddrr,, pprrooggnnuumm,, vveerrssnnuumm,, pprrooccnnuumm,, iinnpprroocc,, iinn,, oouuttpprroocc,, oouutt,, ttoouutt,, ppoorrttpp)) ssttrruucctt ssoocckkaaddddrr__iinn **aaddddrr;; uu__lloonngg pprrooggnnuumm,, vveerrssnnuumm,, pprrooccnnuumm;; cchhaarr **iinn,, **oouutt;; xxddrrpprroocc__tt iinnpprroocc,, oouuttpprroocc;; ssttrruucctt ttiimmeevvaall ttoouutt;; uu__lloonngg **ppoorrttpp;; A user interface to the ppoorrttmmaapp service, which instructs ppoorrttmmaapp on the host at IP address **aaddddrr to make an RPC call on your behalf to a procedure on that host. The parameter **ppoorrttpp will be modified to the program's port number if the procedure succeeds. The definitions of other parameters are discussed in ccaallllrrppcc and ccllnntt__ccaallll. This procedure should be used for a ``ping'' and nothing else. See also ccllnntt__bbrrooaaddccaasstt. Sprite v1.0 3 November 1987 7 RPC C Library Procedures RPC ppmmaapp__sseett((pprrooggnnuumm,, vveerrssnnuumm,, pprroottooccooll,, ppoorrtt)) uu__lloonngg pprrooggnnuumm,, vveerrssnnuumm,, pprroottooccooll;; uu__sshhoorrtt ppoorrtt;; A user interface to the ppoorrttmmaapp service, which estab- lishes a mapping between the triple [pprrooggnnuumm,,vveerrssnnuumm,,pprroottooccooll] and ppoorrtt on the machine's ppoorrttmmaapp service. The value of pprroottooccooll is most likely IIPPPPRROOTTOO__UUDDPP or IIPPPPRROOTTOO__TTCCPP. This routine returns one if it succeeds, zero otherwise. Automatically done by ssvvcc__rreeggiisstteerr. ppmmaapp__uunnsseett((pprrooggnnuumm,, vveerrssnnuumm)) uu__lloonngg pprrooggnnuumm,, vveerrssnnuumm;; A user interface to the ppoorrttmmaapp service, which destroys all mapping between the triple [pprrooggnnuumm,, vveerrssnnuumm,, **] and ppoorrttss on the machine's ppoorrttmmaapp service. This rou- tine returns one if it succeeds, zero otherwise. rreeggiisstteerrrrppcc((pprrooggnnuumm,, vveerrssnnuumm,, pprrooccnnuumm,, pprrooccnnaammee,, iinnpprroocc,, oouuttpprroocc)) uu__lloonngg pprrooggnnuumm,, vveerrssnnuumm,, pprrooccnnuumm;; cchhaarr **((**pprrooccnnaammee)) (()) ;; xxddrrpprroocc__tt iinnpprroocc,, oouuttpprroocc;; Registers procedure pprrooccnnaammee with the RPC service pack- age. If a request arrives for program pprrooggnnuumm, version vveerrssnnuumm, and procedure pprrooccnnuumm, pprrooccnnaammee is called with a pointer to its parameter(s); pprrooggnnaammee should return a pointer to its static result(s); iinnpprroocc is used to decode the parameters while oouuttpprroocc is used to encode the results. This routine returns zero if the regis- tration succeeded, -1 otherwise. Warning: remote procedures registered in this form are accessed using the UDP/IP transport; see ssvvccuuddpp__ccrreeaattee for restrictions. ssttrruucctt rrppcc__ccrreeaatteeeerrrr rrppcc__ccrreeaatteeeerrrr;; A global variable whose value is set by any RPC client creation routine that does not succeed. Use the rou- tine ccllnntt__ppccrreeaatteeeerrrroorr to print the reason why. ssvvcc__ddeessttrrooyy((xxpprrtt)) SSVVCCXXPPRRTT ** xxpprrtt;; A macro that destroys the RPC service transport handle, xxpprrtt. Destruction usually involves deallocation of private data structures, including xxpprrtt itself. Use of xxpprrtt is undefined after calling this routine. Sprite v1.0 3 November 1987 8 RPC C Library Procedures RPC ffdd__sseett ssvvcc__ffddsseett;; A global variable reflecting the RPC service side's read file descriptor bit mask; it is suitable as a parameter to the sseelleecctt system call. This is only of interest if a service implementor does not call ssvvcc__rruunn, but rather does his own asynchronous event processing. This variable is read-only (do not pass its address to sseelleecctt!), yet it may change after calls to ssvvcc__ggeettrreeqqsseett or any creation routines. iinntt ssvvcc__ffddss;; Similar to ssvvcc__ffeeddsseett, but limited to 32 descriptors. This interface is obsoleted by ssvvcc__ffddsseett. ssvvcc__ffrreeeeaarrggss((xxpprrtt,, iinnpprroocc,, iinn)) SSVVCCXXPPRRTT **xxpprrtt;; xxddrrpprroocc__tt iinnpprroocc;; cchhaarr **iinn;; A macro that frees any data allocated by the RPC/XDR system when it decoded the arguments to a service pro- cedure using ssvvcc__ggeettaarrggss. This routine returns one if the results were successfully freed, and zero other- wise. ssvvcc__ggeettaarrggss((xxpprrtt,, iinnpprroocc,, iinn)) SSVVCCXXPPRRTT **xxpprrtt;; xxddrrpprroocc__tt iinnpprroocc;; cchhaarr **iinn;; A macro that decodes the arguments of an RPC request associated with the RPC service transport handle, xxpprrtt .. The parameter iinn is the address where the arguments will be placed; iinnpprroocc is the XDR routine used to decode the arguments. This routine returns one if decoding succeeds, and zero otherwise. ssttrruucctt ssoocckkaaddddrr__iinn ssvvcc__ggeettccaalllleerr((xxpprrtt)) SSVVCCXXPPRRTT **xxpprrtt;; The approved way of getting the network address of the caller of a procedure associated with the RPC service transport handle, xxpprrtt. ssvvcc__ggeettrreeqqsseett((rrddffddss)) ffdd__sseett **rrddffddss;; This routine is only of interest if a service implemen- tor does not call ssvvcc__rruunn, but instead implements Sprite v1.0 3 November 1987 9 RPC C Library Procedures RPC custom asynchronous event processing. It is called when the sseelleecctt system call has determined that an RPC request has arrived on some RPC socket(s); rrddffddss is the resultant read file descriptor bit mask. The routine returns when all sockets associated with the value of rrddffddss have been serviced. ssvvcc__ggeettrreeqq((rrddffddss)) iinntt rrddffddss;; Similar to ssvvcc__ggeettrreeqqsseett, but limited to 32 descrip- tors. This interface is obsoleted by ssvvcc__ggeettrreeqqsseett. ssvvcc__rreeggiisstteerr((xxpprrtt,, pprrooggnnuumm,, vveerrssnnuumm,, ddiissppaattcchh,, pprroottooccooll)) SSVVCCXXPPRRTT **xxpprrtt;; uu__lloonngg pprrooggnnuumm,, vveerrssnnuumm;; vvooiidd ((**ddiissppaattcchh)) (());; uu__lloonngg pprroottooccooll;; Associates pprrooggnnuumm and vveerrssnnuumm with the service dispatch procedure, ddiissppaattcchh. If pprroottooccooll is zero, the service is not registered with the ppoorrttmmaapp service. If pprroottooccooll is non-zero, then a mapping of the triple [pprrooggnnuumm,, vveerrssnnuumm,, pprroottooccooll] to xxpprrtt-->>xxpp__ppoorrtt is esta- blished with the local ppoorrttmmaapp service (generally pprroo-- ttooccooll is zero, IIPPPPRROOTTOO__UUDDPP or IIPPPPRROOTTOO__TTCCPP ). The pro- cedure ddiissppaattcchh has the following form: ddiissppaattcchh((rreeqquueesstt,, xxpprrtt)) ssttrruucctt ssvvcc__rreeqq **rreeqquueesstt;; SSVVCCXXPPRRTT **xxpprrtt;; The ssvvcc__rreeggiisstteerr routine returns one if it succeeds, and zero otherwise. ssvvcc__rruunn(()) This routine never returns. It waits for RPC requests to arrive, and calls the appropriate service procedure using ssvvcc__ggeettrreeqq when one arrives. This procedure is usually waiting for a sseelleecctt system call to return. ssvvcc__sseennddrreeppllyy((xxpprrtt,, oouuttpprroocc,, oouutt)) SSVVCCXXPPRRTT **xxpprrtt;; xxddrrpprroocc__tt oouuttpprroocc;; cchhaarr **oouutt;; Called by an RPC service's dispatch routine to send the results of a remote procedure call. The parameter xxpprrtt is the request's associated transport handle; oouuttpprroocc is the XDR routine which is used to encode the results; and oouutt is the address of the results. This routine returns one if it succeeds, zero otherwise. Sprite v1.0 3 November 1987 10 RPC C Library Procedures RPC vvooiidd ssvvcc__uunnrreeggiisstteerr((pprrooggnnuumm,, vveerrssnnuumm)) uu__lloonngg pprrooggnnuumm,, vveerrssnnuumm;; Removes all mapping of the double [pprrooggnnuumm,, vveerrssnnuumm] to dispatch routines, and of the triple [pprrooggnnuumm,, vveerrssnnuumm,, **] to port number. vvooiidd ssvvcceerrrr__aauutthh((xxpprrtt,, wwhhyy)) SSVVCCXXPPRRTT **xxpprrtt;; eennuumm aauutthh__ssttaatt wwhhyy;; Called by a service dispatch routine that refuses to perform a remote procedure call due to an authentica- tion error. vvooiidd ssvvcceerrrr__ddeeccooddee((xxpprrtt)) SSVVCCXXPPRRTT **xxpprrtt;; Called by a service dispatch routine that can't suc- cessfully decode its parameters. See also ssvvcc__ggeettaarrggss. vvooiidd ssvvcceerrrr__nnoopprroocc((xxpprrtt)) SSVVCCXXPPRRTT **xxpprrtt;; Called by a service dispatch routine that doesn't implement the procedure number that the caller requests. vvooiidd ssvvcceerrrr__nnoopprroogg((xxpprrtt)) SSVVCCXXPPRRTT **xxpprrtt;; Called when the desired program is not registered with the RPC package. Service implementors usually don't need this routine. vvooiidd ssvvcceerrrr__pprrooggvveerrss((xxpprrtt)) SSVVCCXXPPRRTT **xxpprrtt;; Called when the desired version of a program is not registered with the RPC package. Service implementors usually don't need this routine. vvooiidd ssvvcceerrrr__ssyysstteemmeerrrr((xxpprrtt)) SSVVCCXXPPRRTT **xxpprrtt;; Sprite v1.0 3 November 1987 11 RPC C Library Procedures RPC Called by a service dispatch routine when it detects a system error not covered by any particular protocol. For example, if a service can no longer allocate storage, it may call this routine. vvooiidd ssvvcceerrrr__wweeaakkaauutthh((xxpprrtt)) SSVVCCXXPPRRTT **xxpprrtt;; Called by a service dispatch routine that refuses to perform a remote procedure call due to insufficient (but correct) authentication parameters. The routine calls ssvvcceerrrr__aauutthh((xxpprrtt,, AAUUTTHH__TTOOOOWWEEAAKK ) . SSVVCCXXPPRRTT ** ssvvccrraaww__ccrreeaattee(()) This routine creates a toy RPC service transport, to which it returns a pointer. The transport is really a buffer within the process's address space, so the corresponding RPC client should live in the same address space; see ccllnnttrraaww__ccrreeaattee. This routine allows simulation of RPC and acquisition of RPC overheads (such as round trip times), without any kernel interference. This routine returns NULL if it fails. SSVVCCXXPPRRTT ** ssvvccttccpp__ccrreeaattee((ssoocckk,, sseenndd__bbuuff__ssiizzee,, rreeccvv__bbuuff__ssiizzee)) iinntt ssoocckk;; uu__iinntt sseenndd__bbuuff__ssiizzee,, rreeccvv__bbuuff__ssiizzee;; This routine creates a TCP/IP-based RPC service tran- sport, to which it returns a pointer. The transport is associated with the socket ssoocckk, which may be RRPPCC__AANNYYSSOOCCKK ,, in which case a new socket is created. If the socket is not bound to a local TCP port, then this routine binds it to an arbitrary port. Upon com- pletion, xxpprrtt-->>xxpp__ssoocckk is the transport's socket number, and xxpprrtt-->>xxpp__ppoorrtt is the transport's port number. This routine returns NULL if it fails. Since TCP-based RPC uses buffered I/O , users may specify the size of buffers; values of zero choose suitable defaults. vvooiidd ssvvccffdd__ccrreeaattee((ffdd,, sseennssiizzee,, rreeccvvssiizzee)) iinntt ffdd;; uu__iinntt sseennddssiizzee;; uu__iinntt rreeccvvssiizzee;; Creates a service on top of any open desciptor. Typi- cally, this descriptor is a connected socket for a Sprite v1.0 3 November 1987 12 RPC C Library Procedures RPC stream protocol such as TCP . sseennddssiizzee and rreeccvvssiizzee indicate sizes for the send and receive buffers. If they are zero, a reasonable default is chosen. SSVVCCXXPPRRTT ** ssvvccuuddpp__ccrreeaattee((ssoocckk)) iinntt ssoocckk;; This routine creates a UDP/IP-based RPC service tran- sport, to which it returns a pointer. The transport is associated with the socket ssoocckk, which may be RRPPCC__AANNYYSSOOCCKK ,, in which case a new socket is created. If the socket is not bound to a local UDP port, then this routine binds it to an arbitrary port. Upon com- pletion, xxpprrtt-->>xxpp__ssoocckk is the transport's socket number, and xxpprrtt-->>xxpp__ppoorrtt is the transport's port number. This routine returns NULL if it fails. Warning: since UDP-based RPC messages can only hold up to 8 Kbytes of encoded data, this transport cannot be used for procedures that take large arguments or return huge results. xxddrr__aacccceepptteedd__rreeppllyy((xxddrrss,, aarr)) XXDDRR **xxddrrss;; ssttrruucctt aacccceepptteedd__rreeppllyy **aarr;; Used for describing RPC messages, externally. This rou- tine is useful for users who wish to generate RPC-style messages without using the RPC package. xxddrr__aauutthhuunniixx__ppaarrmmss((xxddrrss,, aauupppp)) XXDDRR **xxddrrss;; ssttrruucctt aauutthhuunniixx__ppaarrmmss **aauupppp;; Used for describing UNIX credentials, externally. This routine is useful for users who wish to generate these credentials without using the RPC authentication pack- age. vvooiidd xxddrr__ccaallllhhddrr((xxddrrss,, cchhddrr)) XXDDRR **xxddrrss;; ssttrruucctt rrppcc__mmssgg **cchhddrr;; Used for describing RPC messages, externally. This routine is useful for users who wish to generate RPC- style messages without using the RPC package. xxddrr__ccaallllmmssgg((xxddrrss,, ccmmssgg)) XXDDRR **xxddrrss;; ssttrruucctt rrppcc__mmssgg **ccmmssgg;; Sprite v1.0 3 November 1987 13 RPC C Library Procedures RPC Used for describing RPC messages, externally. This routine is useful for users who wish to generate RPC- style messages without using the RPC package. xxddrr__ooppaaqquuee__aauutthh((xxddrrss,, aapp)) XXDDRR **xxddrrss;; ssttrruucctt ooppaaqquuee__aauutthh **aapp;; Used for describing RPC messages, externally. This routine is useful for users who wish to generate RPC- style messages without using the RPC package. xxddrr__ppmmaapp((xxddrrss,, rreeggss)) XXDDRR **xxddrrss;; ssttrruucctt ppmmaapp **rreeggss;; Used for describing parameters to various ppoorrttmmaapp pro- cedures, externally. This routine is useful for users who wish to generate these parameters without using the ppmmaapp interface. xxddrr__ppmmaapplliisstt((xxddrrss,, rrpp)) XXDDRR **xxddrrss;; ssttrruucctt ppmmaapplliisstt ****rrpp;; Used for describing a list of port mappings, exter- nally. This routine is useful for users who wish to generate these parameters without using the ppmmaapp inter- face. xxddrr__rreejjeecctteedd__rreeppllyy((xxddrrss,, rrrr)) XXDDRR **xxddrrss;; ssttrruucctt rreejjeecctteedd__rreeppllyy **rrrr;; Used for describing RPC messages, externally. This routine is useful for users who wish to generate RPC- style messages without using the RPC package. xxddrr__rreeppllyymmssgg((xxddrrss,, rrmmssgg)) XXDDRR **xxddrrss;; ssttrruucctt rrppcc__mmssgg **rrmmssgg;; Used for describing RPC messages, externally. This routine is useful for users who wish to generate RPC style messages without using the RPC package. vvooiidd xxpprrtt__rreeggiisstteerr((xxpprrtt)) SSVVCCXXPPRRTT **xxpprrtt;; After RPC service transport handles are created, they should register themselves with the RPC service Sprite v1.0 3 November 1987 14 RPC C Library Procedures RPC package. This routine modifies the global variable ssvvcc__ffddss. Service implementors usually don't need this routine. vvooiidd xxpprrtt__uunnrreeggiisstteerr((xxpprrtt)) SSVVCCXXPPRRTT **xxpprrtt;; Before an RPC service transport handle is destroyed, it should unregister itself with the RPC service package. This routine modifies the global variable ssvvcc__ffddss. Service implementors usually don't need this routine. SSEEEE AALLSSOO XXDDRR(3N) The following manuals: _R_e_m_o_t_e _P_r_o_c_e_d_u_r_e _C_a_l_l_s: _P_r_o_t_o_c_o_l _S_p_e_c_i_f_i_c_a_t_i_o_n _R_e_m_o_t_e _P_r_o_c_e_d_u_r_e _C_a_l_l _P_r_o_g_r_a_m_m_i_n_g _G_u_i_d_e _r_p_c_g_e_n _P_r_o_g_r_a_m_m_i_n_g _G_u_i_d_e Sprite v1.0 3 November 1987 15